
 Patch file format
 =================

 A patch-file defines both a number of samples (either as inline
 data or as a pointer to a file containing the samples), and mapping
 from program no. to samples.

 A patch-file starts with a line containing the string "HBP10GM"
 which is followed by a number of fields. The first line in a field
 starts with the field-type; currently, the following field-types
 are supported:   "RAWSAMPLE8"  "RAWSAMPLE16"  "MAPPING"  "NAME" 
 "BANK"  "SAMPLEPART"  "MEMORYSAMPLE8"  "MEMORYSAMPLE16"
 "DRUMNAME" and "DRUMMAPPING"



 RAWSAMPLE16
 RAWSAMPLE8
   This describes a sample stored in a 'raw' file (ie. with no
   header or any other information) in one of the directories
   specified by the 'HBP10GMPatches$Path' variable.
   "RAWSAMPLE8" means that the file contains 8 bit lin signed mono
   samples; "RAWSAMPLE16" means the the file contains 16 bit lin
   signed mono samples; the syntax is:

       "RAWSAMPLE8" <filename> <samplename>
       ["LOOP" <looppoint>]
       <emptyline>

  or   "RAWSAMPLE16" <filename> <samplename>
       ["LOOP" <looppoint>]
       <emptyline>

   where <samplename> is the name of the sample (see below),
   <filename> is the name of the file, relative to HBP10GMPatches;
   the LOOP line is optional (this doesn't mean that the line
   should be left empty, but that it should be omitted completely
   if you don't want to specify a looppoint) - <looppoint> is the
   samplenumber at which playback will restart after the end of the
   sample has been reached or 'NO' if looping is not allowed.
   <emptyline> is an empty line to indicate the end of the field.


 MEMORYSAMPLE8
 MEMORYSAMPLE16
   "MEMORYSAMPLE8" and "MEMORYSAMPLE16" works just like "RAWSAMPLE8"
   and "RAWSAMPLE16", except that the samples are stored in shared
   memory (dynamica area or RMA) and instead of specifying a filename,
   you specify an address and length:

       "MEMORYSAMPLE8" <address> <length> <samplename>
       ["LOOP" <looppoint>]
       <emptyline>

  or   "MEMORYSAMPLE16" <address> <length> <samplename>
       ["LOOP" <looppoint>]
       <emptyline>


 BANK
   This selects which of the 16 instrument-banks the subsequent
   mapping and naming will apply to. Syntax:
       "BANK" <bankno>
   where <bankno> is a number from 1..16.
   If no BANK is specified in a file, bank 1 will be used.


 SAMPLEPART
   This creates a sample from part of another sample.
       "SAMPLEPART" <sourcesamplename>
       <newsamplename> <start> <end>
       ["LOOP" <looppoint>]
       <emptyline>

   <start> and <end> are sample-offsets in the source sample;
   <looppoint> is sample-offset within the new sample or 'NO' if
   looping is not allowed.


 MAPPING
   This defines which programs use which sample(s); syntax:
       "MAPPING" <samplename>
       ["ENVELOPE" <attack> <hold> <decay> <decayamount> <sustain> [<dur>]]
       "MAP" <programno> <frequency> [<octave>]
       <emptyline>
    ENVELOPE defines the envelope to use for any subsequent MAPs -
    there can be any number of ENVELOPE and MAP lines.
    <samplename> is the name of the sample (as described above).
    The ENVELOPE is described below.
    <programno> is the program number that should use the sample or
    a range of program numbers if specified as "[start..end]", eg.
    [0..7]
    <frequency> is the samperate to play the sample at to get
    middle-C or to get the first note (C) in the octave (if <octave>
    is specified); <octave> can be from 1 to 12; <programno> can be
    from 1 to 128. All octaves in a program use the same envelope.


 DRUMMAPPING
    This defines which programs on a drum-channel use which samples;
    the syntax is almost like for MAPPING, except <programno> has
    been replaced with <drumno> (which can be from 1..128) and
    <octave> is not allowed.
       "DRUMMAPPING" <samplename>
       ["ENVELOPE" <attack> <hold> <decay> <decayamount> <sustain> [<dur>]]
       "MAP" <drumno> <frequency>
       <emptyline>


 NAME
    This names a program/patch.
       "NAME" <programno> <patchname>
    <programno> is the program number (1..128) and <patchname> is
    the name of the patch.


 DRUMNAME
    This names a program/patch on the drum-channel(s).
       "DRUMNAME" <programno> <patchname>
    <programno> is the program number (1..128) and <patchname> is
    the name of the patch.


 <samplename> and <patchname> can be up to 15 chars, and may only
 contain the character A..Z a..z 0..9 and _.


 An envelope is defined by the attacktime, the holdtime, the decaytime,
 the decayamount, the sustain-fadeout-rate and optionally also the
 maximum duration of the entire note.
   "ENVELOPE" <attack> <hold> <decay> <decayamount> <sustain> [<dur>]

  <attack>, <hold>, <decay>, <sustain> and <dur> are all in 1/1024th of
  a second. <attack> is the time is takes for the note to fade in to the
  peak volume; <hold> is the time the peak-volume is helt, <decay> is the
  time it takes to fade out to the sustain-start-volume, which is the
  peak volume minus the amount specified by <decayamount> (256=0dB,
  224=-6dB, 192=-12dB etc). During the sustain-part, the volume drops
  a further 6dB in the time specified by <sustain> - if <sustain> is
  0, the volume doesn't drop at all; <dur> is optional and specifies
  the maximum duration of the note; if omitted, the note is allowed to
  sustain infinitely.



 Example of a patch-file:

 HBP10GM
 # load the sample file 'piano3'; name the sample 'GrandPiano'
 # and disable looping
 RAWSAMPLE8 piano3 GrandPiano
 LOOP NO

 # switch to patch bank #2
 BANK 2
 # create a new sample from the first 7065 samples
 # in the sample named 'GrandPiano'; the new sample
 # is named 'GrandPiano1' and doesn't allow looping
 SAMPLEPART GrandPiano
 GrandPiano1 0 7065
 LOOP NO

 # map the sample 'GrandPiano1' to program no #1
 # use a simple envelope; playback at 20kHz gives middle-C
 MAPPING GrandPiano1
 ENVELOPE 10 0 10 256 3000
 MAP 1 20000

 # name program no #1 'AcGrandPiano12'
 NAME 1 AcGrandPiano12

